---
title: Block Selection
description: Select and manipulate entire text blocks.
---

<ComponentPreview name="playground-demo" id="blockselection" scrollSelector="block-selection-plugin" />

<PackageInfo>

## Features

- Select entire blocks, as opposed to individual words or characters.
- To select an entire block, mouse down outside the text area and then move the cursor into the block. Once it is selected, you'll see a background color.
- Keep moving down or up to select multiple blocks.
- Once selected, the available actions are: copy, cut, and delete.
- Keyboard shortcuts:
  - `Cmd+A` (Mac) / `Ctrl+A` (Windows/Linux): 
    - First press: Selects the current block
    - Double press: Selects the whole document using block selection
  - Note: This behavior can be disabled by setting `handlers.onKeyDown = null` when creating the plugin

</PackageInfo>

## Installation

```bash
npm install @udecode/plate-selection @udecode/plate-node-id
```

## Usage

```tsx
import { NodeIdPlugin } from '@udecode/plate-node-id';
import { BlockSelectionPlugin } from '@udecode/plate-selection/react';

const plugins = [
  // ...otherPlugins,
  NodeIdPlugin,
  BlockSelectionPlugin,
];
```

## Set scrollable container

To control the scrollable container, configure the `boundaries` and `container` options within `areaOptions`. These options accept CSS selectors, such as `#selection-demo #scroll_container`, which are used with `document.querySelector()`.

For this to work effectively:

1. Add an `id` or `className` to your scroll container.
2. Use the appropriate selector in your configuration.

Example configuration:

```js
{
  areaOptions: {
    boundaries: '#your-scroll-container-id',
    container: '#your-scroll-container-id',
    selectables: '#your-scroll-container-id .slate-selectable',
    selectionAreaClass: 'slate-selection-area',
  }
}
```

This setup ensures that the block selection functionality is properly constrained within your designated scrollable area.

## Set selectable element

Add data-plate-selectable to the container or the element you want to start block selection.

Example:
```tsx
   <PlateContent
    aria-disabled={disabled}
    className={cn(
      editorVariants({
        disabled,
        focusRing,
        focused,
        size,
        variant,
      }),
      className
    )}
    data-plate-selectable
    disableDefaultStyles
    readOnly={disabled ?? readOnly}
    {...props}
    />
```

### Styling


#### Selection area
You can style the selection area by adding this class to the container(.slate-selection-area can be changed in the plugin options):

```js
'[&_.slate-selection-area]:border [&_.slate-selection-area]:border-primary [&_.slate-selection-area]:bg-primary/10'
```

#### Selected element

You can style the selected element by adding this class to the container

```js
'[&]:!bg-primary/20'
```




### Disable browser default scroll behavior
If we select some text and then move(keep pressed) the cursor to the very bottom of the page, the page will start scrolling to the bottom.

This scroll is so fast and confilicts with `BlockSelectionPlugin` scroll behavior(After the selection area appears, move the mouse to the bottom of the scroll container).

I don't find any way to disable this scroll behavior of browser.(if you find the way to disable it, please tell me that will so appreciate it)So the solution is add an empty `div` above the editer's right side(The right side is the easiest place to trigger this behavior.) and set `user-select: none` to it .

If you find this issue occurring in your editor, please check the width of this div. You can use the option `editorPaddingRight` to set the width of this div or the class `rightSelectionAreaClassName` to style it.

Make sure the width is the same with the editor's padding-right.

## Plugins

### BlockSelectionPlugin

<APIOptions>
<APIItem name="areaOptions" type="PartialSelectionOptions" optional>
Options for the selection area. Example:

```ts
{
  boundaries: ['#selection-demo #scroll_container'],
  container: ['#selection-demo #scroll_container'],
  selectables: ['#selection-demo #scroll_container .slate-selectable'],
  selectionAreaClass: 'slate-selection-area',
}
```
</APIItem>

<APIItem name="editorPaddingRight" type="CSSProperties['width']" optional>
The padding-right of the editor.
</APIItem>

<APIItem name="enableContextMenu" type="boolean" optional>
Enables or disables the context menu for block selection.

- **Default:** `false`
</APIItem>

<APIItem name="isSelecting" type="boolean" optional>
Indicates whether block selection is currently active.

- **Default:** `false`
</APIItem>

<APIItem name="onKeyDownSelecting" type="(e: KeyboardEvent) => void" optional>
A function to handle the **`keydown`** event when selecting.
</APIItem>

<APIItem name="query" type="QueryNodeOptions" optional>
Options for querying nodes during block selection.

- **Default:** `{ maxLevel: 1 }`
</APIItem>

<APIItem name="selectedIds" type="Set<string>" optional>
A set of IDs for the currently selected blocks.

- **Default:** `new Set()`
</APIItem>
</APIOptions>

### BlockContextMenuPlugin

This plugin is used by `BlockSelectionPlugin` and doesn't need to be added manually.

## API

### editor.api.blockSelection.addSelectedRow

Adds a selected row to the block selection.

<APIParameters>
  <APIItem name="id" type="string">
    The ID of the row to be selected.
  </APIItem>
  <APIItem name="options" type="object" optional>
    <APISubList>
      <APISubListItem parent="options" name="aboveHtmlNode" type="HTMLDivElement" optional>
        The HTML node above which to add the selection.
      </APISubListItem>
      <APISubListItem parent="options" name="clear" type="boolean" optional>
        Whether to clear existing selections before adding the new one.
        - **Default:** `true`
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIParameters>

### editor.api.blockSelection.getSelectedBlocks

Gets the selected blocks in the editor.

<APIReturns>
  <APIItem type="TNodeEntry[]">
    An array of selected block entries.
  </APIItem>
</APIReturns>

### editor.api.blockSelection.resetSelectedIds

Resets the set of selected IDs to an empty set.

### editor.api.blockSelection.selectedAll

Selects all selectable blocks in the editor.

### editor.api.blockSelection.setSelectedIds

Sets the selected IDs based on added and removed elements.

<APIParameters>
  <APIItem name="options" type="ChangedElements">
    <APISubList>
      <APISubListItem parent="options" name="added" type="HTMLElement[]">
        Array of HTML elements to be added to the selection.
      </APISubListItem>
      <APISubListItem parent="options" name="removed" type="HTMLElement[]">
        Array of HTML elements to be removed from the selection.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIParameters>

### editor.api.blockSelection.unselect

Unselects all blocks and sets the `isSelecting` flag to false.

## API Components

### BlockSelectable

<APIProps>
  <APIItem name="options" type="BlockSelectableOptions">
    <APISubList>
      <APISubListItem parent="options" name="element" type="TElement">
        The element to render the block selectable.
      </APISubListItem>
      <APISubListItem parent="options" name="active" type="boolean" optional>
        Whether the selection is active.
      </APISubListItem>
    </APISubList>
  </APIItem>
</APIProps>

### BlockSelection

A wrapper component that adds block selection functionality to its children.

<APIProps>
  <APIItem name="children" type="React.ReactNode">
    The content to be wrapped with block selection functionality.
  </APIItem>
</APIProps>

## Hooks

### useBlockSelectableState

<APIReturns>
  <APIItem name="active" type="boolean">
    Whether the block is active for selection.
  </APIItem>
  <APIItem name="element" type="TElement" optional>
    The element associated with the block.
  </APIItem>
  <APIItem name="path" type="Path" optional>
    The path of the block in the editor.
  </APIItem>
  <APIItem name="ref" type="React.RefObject<HTMLDivElement>" optional>
    A ref to the block's DOM element.
  </APIItem>
</APIReturns>

### useBlockSelectable

<APIReturns>
  <APIItem name="props" type="object">
    Props to be spread on the block's wrapper element.
  </APIItem>
</APIReturns>

### useSelectionArea

A hook that initializes and manages the selection area functionality.